home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Gold Medal Software 3
/
Gold Medal Software - Volume 3 (Gold Medal) (1994).iso
/
prog
/
panshr24.arj
/
PANELS24.DOC
< prev
next >
Wrap
Text File
|
1993-11-17
|
16KB
|
478 lines
▒▒▒▒▒▒▄ ▒▒▒▒▒▒▄ ▒▒▒▄▄ ▒▒▄ ▒▒▒▒▒▒▄ ▒▒▄ ▒▒▒▒▒▒▄ ▒▒▒▒▒▒▄
▒▒█▀▒▒█ ▒▒█▀▒▒█ ▒▒█▒▒█▒▒█ ▒▒█▀▀▀▀ ▒▒█ ▒▒█▀▀▀▀ F ▒▒█▀▀▀▀
▒▒▒▒▒▒█ ▒▒▒▒▒▒█ ▒▒█ ▀▒▒▒█ ▒▒▒▒▒▄ ▒▒█ ▒▒▒▒▒▒▄ O ▒▒█
▒▒█▀▀▀▀ ▒▒█ ▒▒█ ▒▒█ ▒▒█ ▒▒█▀▀▀ ▒▒█ ▀▀▀▒▒█ R ▒▒█
▒▒█ ▒▒█ ▒▒█ ▒▒█ ▒▒█ ▒▒▒▒▒▒▄ ▒▒▒▒▒▒▄ ▒▒▒▒▒▒█ ▒▒▒▒▒▒▄
▀▀ ▀▀ ▀▀ ▀▀ ▀▀ ▀▀▀▀▀▀ ▀▀▀▀▀▀ ▀▀▀▀▀▀ ▀▀▀▀▀▀
Version 2.4
A User Interface
BC Systems
7801 Dublin
Wichita, KS 67206
CIS: 73171,2442
Copyright 1989-1993, Jay Brown
I. Overview
"Panels for C" is a set of routines which may be called by your
Application program to do screen oriented input and output. Screen
layouts, or panels, are simple text files that you can create with
an ordinary word processor. Panels always have a file extension of
PAN. The format of a panel is covered in a later section.
A panel definition may reside in its own file separate from your
application source code, or it may be defined as a string within
your application code. The advantage for a separate file is the
interpreted nature of the screen layout. The panel may be changed
without recompiling the application program. The advantage of
using a string to define the panel is reduced disk I/O during the
execution of your program.
The author recommends that during the development of an
application, panels are defined within their own files. When an
application is compiled for production, you may consider moving the
panel definitions to the program source for efficiency and
security. A utility call PAN2H has been created to translate a
panel file to a C header file. Also, a utility to simplify the
creation and modification of panels has been developed, called IPD
(Interactive Panel Design).
Panels for C is distributed as shareware. This software is
protected by copyright laws. Users may register by purchasing
either the object or source packages, see the enclosed order form.
Registered users can expect the software to be supported by the
publisher. Also, notification of future releases can be expected.
BC Systems grants to purchasers of either object or source packages
a no-fee license to resell applications created with the Panel
routines. The only constraint is that the application code and
documentation MUST contain the following acknowledgement:
Portions copyright 1989-1993, J. Brown.
II. Executing a Panels Program
While a panel is active, during the execution of a panels
application program, the following keys are used for data input:
<Right Tab> Moves cursor to the next unprotected screen field.
<Left Tab> Moves cursor to the previous unprotected screen
field.
<Enter> Moves cursor to the first unprotected screen field
on the next line.
<Home> Moves cursor to the first unprotected screen field.
<End> Move cursor to the end of the current field.
<Ins> Toggles insert mode on and off. The cursor is a
little larger when insert mode is on.
<Del> Deletes the character under the cursor.
<Ctrl><End> Erase to end of field.
<Arrows> Moves the cursor in the appropriate direction,
possibly into a protected area. A click will be
heard, if attempting to enter data into a protected
area.
<Func keys> <Page Up> <Page Down> <Esc>
When one of these keys is pressed execution returns
to the application program. These response keys
are the default, and any keystroke can be
configured as a response key by the application
programmer.
III. Panel Design
Text File Format
A panel text file begins with an optional size statement followed
by an optional background statement. One or more tag statements
are used to relate field attributes and field names to special
characters or symbols. After the tag statements is the actual
screen layout, which must begin with a tagged symbol.
size <ul_row> <ul_col> <lr_row> <lr_col>
background <color>
tag <sym> <attr> [<variable list>]
.
.
.
<symbol>..................................
..........................................
..........................................
.
.
.
Size Statement
This is an optional panel statement, and if present must precede
the background statement or the first tag statement. This
statement simply sets the size and location of the window in which
the panel will be constructed.
Format:
size <ul_row> <ul_col> <lr_row> <lr_col>
where:
<ul_row> upper left row of the window
<ul_col> upper left column of the window
<lr_row> lower right row of the window
<lr_col> lower right window column
Example:
size 0 0 13 39 Defines a panel to be 14 rows by 40 columns
located in the upper left part of the screen.
If a size statement is not present within a panel definition, the
default window coordinates are 0,0 and 24,79. If a panel is
defined to be smaller than the previous active panel, the previous
panel will be partially visible behind the new panel. However, the
overlaid panel will not be active again until the new panel is
destroyed (i.e. no I/O functions may be performed on the previous
panel).
Background Statement
This is an optional panel statement, and if present must precede
the first tag statement. This statement simply sets the screen
background color when a color adapter is in use. If a monochrome
adapter is in use the background statement is ignored.
Format:
background <color>
where: <color> is a digit 0 - 7
Color codes: 0 = Black (Default)
1 = Blue
2 = Green
3 = Cyan
4 = Red
5 = Magenta
6 = Brown
7 = White
Tag Statement
A tag statement allows you to relate a special character or symbol
with a field definition. This definition includes the field
attributes as well as the field names.
Format:
tag <sym> <attr> [<variable list>]
where:
<sym> is one character symbol not used anywhere on the
actual screen layout. This symbol will relate
screen attributes and field names to specific
locations on the screen.
<Attr> is the field attribute.
Attribute codes:
P = Protected
U = Unprotected (Default)
H = High Intensity
L = Low Intensity (Default)
B = Blink
R = Reverse
_ = Underline
D = Dark
0 = Black
1 = Blue
2 = Green
3 = Cyan
4 = Red
5 = Magenta
6 = Brown
7 = White (Default)
Some attributes may have no effect with certain monitor types (i.e.
the color codes will have no effect when using a monochrome display
adapter). Some attributes are mutually exclusive -- either P or U
may be used, but not both; either H or L may be used; and only one
color code may be specified.
<variable list> One or more field names separated by at least
one blank. Valid names are no more than eight
characters beginning with a letter. No
special characters are allowed.
Each variable or field name is matched to a field on the screen
layout. If more fields are defined with the tag symbol than
variables in the list, the last variable name in the list is used
to name the remaining fields. In this case, a subscript other than
1 is used to access like named fields.
Examples
In this example, there are two unprotected fields. The first field
may be accessed using the name FIELD subscripted by 1, and the
second field is referenced as FIELD with a subscript of 2.
The screen background color is defined to be blue. The ! symbol
defines protected red fields. The @ symbol defines protected,
reverse fields with white characters. The asterisk tagged field is
named SELECT and will be unprotected, underlined and green.
The screen background color is defined to be white. The ! symbol
defines protected red fields. This example demonstrates the use of
the size statement. The panel is defined as a 7 x 27 character box
to be displayed in the lower right part of the screen.
Panel Design
Try your hand at designing your own panel! Use any word processor
to create the panel file. Be sure your file has an extension of
PAN.
Optionally, you may use IPD to create and modify a panel, type:
ipd [<fn>]
After your panel text file has been created, type:
showpan <fn>
where <fn> is your panel file name without the .PAN extension.
IV. Programming with Panels
Only a few Panel routines are needed to do complete screen level
I/O with your application program. What follows here and on
subsequent pages is a description of each routine available to link
with your program.
void pan_init();
This routine is used to initialize the Panels for C
environment. It determines what video adapter is in use, etc.
This function must be called before any of the other functions
are used.
void pan_activate(char *fn);
This routine will paint the screen using the panel defined in
the text file <fn>.pan. Memory is allocated for a panel
variable table. If a panel was previously active it will
exist behind the new panel. Optionally, the character string
<fn> may be a complete panel definition. The activate
function determines whether the string is a file name or a
panel definition by the presence or absence of a newline
character within the string. A file name will not have a
newline character in it.
unsigned pan_execute(char *name,
int sub,
int alarm);
Positions the cursor to the named field or first unprotected
field if name is NULL. Sub is the subscript of the name
field. A bell will sound if alarm is true. Control will
return from this routine when a response key is pressed. The
response key code (as defined in keys.h ) is the return value.
The following is a list of global variables assigned values by
the pan_execute function:
pan_row Indicates the row on which the
cursor was placed prior to detecting
a response key from the user.
pan_col Indicates the column on which the
cursor was placed prior to detecting
a response key from the user.
pan_field_name Indicates the current field name under
the cursor when the user pressed a
response key.
pan_field_sub Indicates the current field subscript
under the cursor when the user pressed a
response key.
void pan_destroy();
This routine frees memory occupied by the panel variable table
and restores the panel behind the active panel if present.
void pan_field_attr(char *name,
int sub,
char *attr);
Changes the screen attributes of the named panel field after
the panel has been activated. Useful for indicating an error
to the user by highlighting or blinking the contents of the
erroneous field.
void pan_put_field(char *name,
int sub,
char *value);
This routine transfers value to the named panel field.
void pan_get_field(char *name,
int sub,
char *value);
This routine transfers the named panel field to value .
void pan_sound(int freq, int dur);
Produces a sound of freq frequency and at least dur duration
on the speaker. The duration is in hundredths of a second.
void pan_delay(int dur);
Wait for at least dur hundredths of a second to elapse.
unsigned pan_get_key();
Wait for a keystroke from the user and return the key code as
defined within the keys.h header file.
void pan_idle_func(int (*func)());
Sets up a user supplied function to be called while
panel_execute or get_key is waiting for a keystroke from the
user. func is a pointer to a function which returns an
integer value. The NULLF value, defined within panel.h may be
used to disable an idle function call.
void pan_error(16, int line, char *msg);
Abort the application program by cleaning up any active
panels. This function then displays the msg parameter and
line number if not zero. The abort code of 16 should be used
by the application program, other codes are used within the
panel routines.
void pan_resp_keys(unsigned exitkeys[]);
This function allows the programmer to override the default
response keys. An array of unsigned integers is passed. The
last value within the exitkeys table must be zero.
PAN_LIST *pan_linit();
Allocate and initialize a list pick structure. This function
returns a pointer to the list pick structure.
void pan_ladd(PAN_LIST *list, char *desc, void *data);
Add a list pick element to the indicated list structure. desc
is the text to appear in the list, and "data" is anything
associated with the element and hidden from the user.
void pan_lfree(PAN_LIST *list, int free_desc, int free_data);
Free all memory associated with the indicated list structure.
"free_desc" is a flag indicating whether to free memory
associated with each list item description. "free_data" is a
flag indicating whether to free memory associated with each
hidden data object.
void pan_lact(PAN_LIST *list);
This function activates the indicated list structure, i.e.
makes it visible to the user.
unsigned pan_lexec(PAN_LIST *list);
This function executes the indicated list structure, i.e.
allows the user to make a selection. The exit key code is
returned by this function.
V. Compilation and Linkage
Included in the Panels for C package is one or more of the
following object files:
SPANELR.OBJ MicroSoft C DOS small model
LPANELR.OBJ MicroSoft C DOS large model
SPANELP.OBJ MicroSoft C OS/2 small model
LPANELP.OBJ MicroSoft C OS/2 large model
SPANELTC.OBJ Turbo C DOS small model
LPANELTC.OBJ Turbo C DOS large model
MicroSoft C
Assuming you have written a DOS program to be compiled with
MicroSoft C, you could use one of the following commands to compile
and link it with the Panel routines:
Small model:
cl /AS /F 2000 YourPgm.c spanelr.obj
Large model:
cl /AL /F 2000 YourPgm.c lpanelr.obj
The /F option sets the size of the program stack for the executable
file. This must be set to an adequate value. A makefile is also
included in the package to illustrate how panel programs are built.
Turbo C
Using the Turbo C integrated development environment, create a
project file with your source file name and either SPANELTC.OBJ or
LPANELTC.OBJ listed in it. Select the make EXE option from the
compile menu.
For other compilers, consult your reference manual. Be sure to
include the files PANEL.H and KEYS.H in your source code.